home *** CD-ROM | disk | FTP | other *** search
/ Directorty Opus 5 - Magellan / Opus 5 - Magellan.iso / Extras / opussdk / docs / icon.doc < prev    next >
Text File  |  1996-09-05  |  8KB  |  274 lines
  1. TABLE OF CONTENTS
  2.  
  3. dopus5.library/FreeCachedDiskObject
  4. dopus5.library/GetCachedDefDiskObject
  5. dopus5.library/GetCachedDiskObject
  6. dopus5.library/GetCachedDiskObjectNew
  7. dopus5.library/GetIconFlags
  8. dopus5.library/GetIconPosition
  9. dopus5.library/SetIconFlags
  10. dopus5.library/SetIconPosition
  11. dopus5.library/CopyFileIcon
  12. dopus5.library/FreeCachedDiskObject       dopus5.library/FreeCachedDiskObject
  13.  
  14.     NAME
  15.         FreeCachedDiskObject - free a cached icon
  16.  
  17.     SYNOPSIS
  18.         FreeCachedDiskObject(icon)
  19.                               A0
  20.  
  21.         void FreeCachedDiskObject(struct DiskObject *);
  22.  
  23.     FUNCTION
  24.         This function frees a cached icon obtained via a call to
  25.         GetCachedDiskObject() or a similar function.
  26.  
  27.     INPUTS
  28.         icon - icon to free
  29.  
  30.     RESULT
  31.         The usage count of the cached icon is decremented. When the usage
  32.         count reaches zero, the icon is flushed from the cache.
  33.  
  34.     NOTES
  35.         You can pass a normal, uncached icon to this routine, in which case
  36.         it just passes the call through to FreeDiskObject().
  37.  
  38.     SEE ALSO
  39.         GetCachedDiskObject(), icon.library/FreeDiskObject()
  40.  
  41. dopus5.library/GetCachedDefDiskObject   dopus5.library/GetCachedDefDiskObject
  42.  
  43.     NAME
  44.         GetCachedDefDiskObject - GetDefDiskObject() with image caching
  45.  
  46.     SYNOPSIS
  47.         GetCachedDefDiskObject(type)
  48.                                 D0
  49.  
  50.         struct DiskObject *GetCachedDefDiskObject(long);
  51.  
  52.     FUNCTION
  53.         This routine returns one of a number of default icons. The main
  54.         advantage this has over the icon.library GetDefDiskObject() call is
  55.         that the image data of the icons is cached. This can save a huge
  56.         amount of chip memory if multiple copies of the same icon are
  57.         required (compare the chip memory used when you open a large drawer
  58.         in Workbench with the same drawer in Opus).
  59.  
  60.     INPUTS
  61.         type - type of icon to create
  62.  
  63.     RESULT
  64.         Returns a pointer to the icon or NULL for failure.
  65.  
  66.     SEE ALSO
  67.         FreeCachedDiskObject(), icon.library/GetDefDiskObject()
  68.  
  69. dopus5.library/GetCachedDiskObject         dopus5.library/GetCachedDiskObject
  70.  
  71.     NAME
  72.         GetCachedDiskObject - get an icon from disk with image caching
  73.  
  74.     SYNOPSIS
  75.         GetCachedDiskObject(name)
  76.                              A0
  77.  
  78.         struct DiskObject *GetCachedDiskObject(char *);
  79.  
  80.     FUNCTION
  81.         This routine loads an icon from disk, and caches the image data. If
  82.         the same icon is loaded again, the cached image data is used instead
  83.         of loading a new copy. This can save valuable chip memory, especially as
  84.         the cache is system wide.
  85.  
  86.     INPUTS
  87.         name - name of icon to load (without the .info suffix)
  88.  
  89.     RESULT
  90.         Returns a pointer to the icon if successful, otherwise NULL.
  91.  
  92.     NOTES
  93.         You should not use this routine if you want to modify the image data.
  94.         Only the image data is cached, however, so you can modify any of the
  95.         other fields of the icon.
  96.  
  97.         Also, this routine is slightly slower than a normal call to
  98.         GetDiskObject(), and while the icon is loading requires slightly more
  99.         memory (the whole icon is loaded, then if the image is found in the
  100.         cache the new copy is discarded).
  101.  
  102.     SEE ALSO
  103.         FreeCachedDiskObject(), icon.library/GetDiskObject
  104.  
  105. dopus5.library/GetCachedDiskObjectNew   dopus5.library/GetCachedDiskObjectNew
  106.  
  107.     NAME
  108.         GetCachedDiskObjectNew - get icon with default fallback
  109.  
  110.     SYNOPSIS
  111.         GetCachedDiskObjectNew(name)
  112.                                 A0
  113.  
  114.         struct DiskObject *GetCachedDiskObjectNew(char *);
  115.  
  116.     FUNCTION
  117.         This routine attempts to load the icon in the same way as the
  118.         GetCachedDiskObject() routine. If no icon is found for the supplied
  119.         filename, the object in question is examined, and a default icon is
  120.         returned. This routine will return WBPROJECT, WBDRAWER, WBTOOL or
  121.         WBDISK icons, depending on the name passed in.
  122.  
  123.     INPUTS
  124.         name - name of object to load icon for (no .info suffix)
  125.  
  126.     RESULT
  127.         Returns a pointer to the icon if successful, otherwise NULL.
  128.  
  129.     SEE ALSO
  130.         GetCachedDiskObject(), FreeCachedDiskObject(),
  131.         icon.library/GetDiskObjectNew()
  132.  
  133. dopus5.library/GetIconFlags                       dopus5.library/GetIconFlags
  134.  
  135.     NAME
  136.         GetIconFlags - get special Opus icon flags
  137.  
  138.     SYNOPSIS
  139.         GetIconFlags(icon)
  140.                       A0
  141.  
  142.         ULONG GetIconFlags(struct DiskObject *);
  143.  
  144.     FUNCTION
  145.         Opus stores additional information in icons to control some of the
  146.         enhanced features. This routine returns the special flags set for the
  147.         icon you supply.
  148.  
  149.     INPUTS
  150.         icon - icon to retrieve flags for
  151.  
  152.     RESULT
  153.         Returns ULONG containing the flags set. Current flags in use are :
  154.  
  155.             ICONF_POSITION_OK   - an Opus-specific position is available
  156.             ICONF_NO_BORDER     - icon has no border
  157.             ICONF_NO_LABEL      - icon has no label
  158.  
  159.     SEE ALSO
  160.         SetIconFlags(), GetIconPosition()
  161.  
  162. dopus5.library/GetIconPosition                 dopus5.library/GetIconPosition
  163.  
  164.     NAME
  165.         GetIconPosition - get Opus-specific icon position
  166.  
  167.     SYNOPSIS
  168.         GetIconPosition(icon, xptr, yptr)
  169.                          A0    A1    A2
  170.  
  171.         void GetIconPosition(struct DiskObject *, short *, short *);
  172.  
  173.     FUNCTION
  174.         Opus keeps a separate record from Workbench of icon positions. This
  175.         function allows you to retrieve the Opus-specific position of the
  176.         icon (the normal Workbench position is in do_CurrentX/do_CurrentY).
  177.  
  178.     INPUTS
  179.         icon - icon to retrieve position for
  180.         xptr - pointer to short to receive x position
  181.         yptr - pointer to short to receive y position
  182.  
  183.     RESULT
  184.         Stores the position in the two variables provided.
  185.  
  186.     NOTES
  187.         You should call GetIconFlags() first to check that an Opus-specific
  188.         position is available for this icon.
  189.  
  190.     SEE ALSO
  191.         SetIconPosition(), GetIconFlags()
  192.  
  193. dopus5.library/SetIconFlags                       dopus5.library/SetIconFlags
  194.  
  195.     NAME
  196.         SetIconFlags - set Opus flags in an icon
  197.  
  198.     SYNOPSIS
  199.         SetIconFlags(icon, flags);
  200.                       A0     D0
  201.  
  202.         void SetIconFlags(struct DiskObject *, ULONG);
  203.  
  204.     FUNCTION
  205.         This routine allows you to set the special Opus flags in an icon.
  206.  
  207.     INPUTS
  208.         icon - icon to set flags for
  209.         flags - new flags for the icon
  210.  
  211.     RESULT
  212.         The flags in the icon are set. See GetIconFlags() for a description
  213.         of the available flags.
  214.  
  215.     SEE ALSO
  216.         GetIconFlags()
  217.  
  218. dopus5.library/SetIconPosition                 dopus5.library/SetIconPosition
  219.  
  220.     NAME
  221.         SetIconPosition - set Opus position for an icon
  222.  
  223.     SYNOPSIS
  224.         SetIconPosition(icon, x, y)
  225.                          A0  D0 D1
  226.  
  227.         void SetIconPosition(struct DiskObject *, short, short);
  228.  
  229.     FUNCTION
  230.         This routine allows you to set the Opus-specific position for an
  231.         icon.
  232.  
  233.     INPUTS
  234.         icon - icon to set position for
  235.         x - new x position of icon
  236.         y - new y position of icon
  237.  
  238.     RESULT
  239.         The position is set in the icon.
  240.  
  241.     NOTES
  242.         You should also call SetIconFlags() on the icon to set the
  243.         ICONF_POSITION_OK flag.
  244.  
  245.     SEE ALSO
  246.         GetIconPosition(), SetIconFlags()
  247.  
  248. dopus5.library/CopyFileIcon                       dopus5.library/CopyFileIcon
  249.  
  250.     NAME
  251.         CopyFileIcon - copy icon from one file to another
  252.  
  253.     SYNOPSIS
  254.         CopyFileIcon(source, dest)
  255.                          A0     A1
  256.  
  257.         void CopyFileIcon(char *, char *);
  258.  
  259.     FUNCTION
  260.         This routine copies the icon from the specified source object to a
  261.         new icon for the destination object.
  262.  
  263.     INPUTS
  264.         source - source icon (without .info)
  265.         dest - destination icon (without .info)
  266.  
  267.     RESULT
  268.         The icon is copied. If an icon already exists for the source, it is
  269.         NOT overwritten. No error code is available for this function.
  270.  
  271.     NOTES
  272.         If the specified source file has no icon, a default icon is created.
  273.  
  274.